Remove mention of config SO types from SO.create API docs. #168538
Conversation
lukeelmers
added
Team:Core
|
Pinging @elastic/kibana-core (Team:Core) |
|
Documentation preview: |
There was a problem hiding this comment.
I agree with the PR description comment that these configuration objects are created automatically.
Even though it's possible to create a new one using the API directly, or even copying an existing document and editing it, these "custom" docs often cause more issues than what they're worth. Only users who know what they're doing should be creating these on the fly, although even then I wouldn't recommended.
Configuration is an onion: there are many layers to it, some settings are declared by apps, others by services and then we also have global config! It's hard to keep track of how all of these compile and what overrides what.
This PR is a step in the right direction: we shouldn't mention config, since users don't need to create one for Kibana to work and we don't recommend they do so anyway.
LGTM!
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
…68538) (#169130) # Backport This will backport the following commits from `main` to `8.11`: - [Remove mention of config SO types from SO.create API docs. (#168538)](#168538) <!--- Backport version: 8.9.7 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Luke Elmers","email":"[email protected]"},"sourceCommit":{"committedDate":"2023-10-17T15:40:49Z","message":"Remove mention of config SO types from SO.create API docs. (#168538)","sha":"6df50ea66679478288ec67150c9ed5aab8b8e637","branchLabelMapping":{"^v8.12.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Core","release_note:skip","docs","backport:prev-minor","v8.12.0"],"number":168538,"url":"https://github.com/elastic/kibana/pull/168538","mergeCommit":{"message":"Remove mention of config SO types from SO.create API docs. (#168538)","sha":"6df50ea66679478288ec67150c9ed5aab8b8e637"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.12.0","labelRegex":"^v8.12.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/168538","number":168538,"mergeCommit":{"message":"Remove mention of config SO types from SO.create API docs. (#168538)","sha":"6df50ea66679478288ec67150c9ed5aab8b8e637"}}]}] BACKPORT--> Co-authored-by: Luke Elmers <[email protected]>
In our docs for the saved objects
createhttp APIs, we mentionconfigas a supported SO type. While technically possible to create aconfigSO via the API, I don't think it is advisable because Kibana generates these automatically. I think it is fine if someone wants to edit/update an existingconfigobject, but I wonder if we should exclude mention of it for thecreateendpoints specifically?